docs: explain IPv6 localhost resolution for published sandbox ports#25200
Conversation
Document the gotcha where `--publish` listens on both `127.0.0.1` and `::1` while many dev servers bind only to IPv4 — clients resolving `localhost` to IPv6 then fail with "connection reset by peer". Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
|
||
| - **Services must bind to `0.0.0.0`** — a service listening on `127.0.0.1` | ||
| inside the sandbox won't be reachable through a published port. Most dev | ||
| - **Services must listen on all interfaces** — a service listening only on |
There was a problem hiding this comment.
[MEDIUM] Prohibited **Term** — Description list format in new bullets
Both new bullets use the **Bold term** — description pattern that the Docker style guide explicitly prohibits in lists (STYLE.md: "Avoid marketing-style list formatting — Don't use 'Term - Description' format, which reads like marketing copy"). The same rule also means bold should only appear on UI elements (buttons, menus, field labels), not on technical concept labels.
The existing bullets in this list already have this pattern, but this PR adds two more instances. Consider reformatting as plain descriptive bullets — for example:
- Services must listen on all interfaces: a service listening only on
`127.0.0.1` inside the sandbox won't be reachable through a published port.
Bind to `0.0.0.0` for IPv4, or `[::]` to accept both IPv4 and IPv6. Most dev
servers default to `127.0.0.1`, so you'll usually need to pass a flag like
`--host 0.0.0.0` or `--host '[::]'` when starting them.
- `localhost` on the host can resolve to IPv6: by default, `--publish`
listens on both `127.0.0.1` and `::1`. ...Or use plain prose. Note: the pre-existing bullets (Not persistent, No create-time flag, Unpublish requires the host port) have the same formatting issue — it may be worth fixing those at the same time.
3 participants
Description
Documents a gotcha with
sbx ports --publishwhere clients resolvinglocalhostto IPv6 fail with "connection reset by peer", even thoughhttp://127.0.0.1:<port>/works.When no host IP is given to
--publish, the host listener binds to both127.0.0.1and::1. Many dev servers (Vite,code-serverwith--bind-addr 0.0.0.0:8080, etc.) only listen on IPv4 inside the sandbox, so any client that picks IPv6 forlocalhosthits a dead end.Two changes to the bullet list under Accessing services in the sandbox:
0.0.0.0" bullet to also mention[::]for dual-stack listeners.localhostfailure mode and the two fixes: bind the sandboxed service to[::], or restrict the published port with/tcp4(or/tcp6).Context: internal Slack thread where two users hit this independently.